<html>
    <head>
        <title>Working with Kiki
        </title>
    </head>
    <body>
        <table cellspacing="0" cellpadding="0">
        
            <tr><td bgcolor="#EAEAEA">
                    <b><font size="4">Intro</font></b>
            </td></tr>
            <tr><td>
                Kiki is a free environment for regular expression testing (ferret).
                It allows you to write regexes and test them against your sample
                text, providing extensive output about the results. It is useful
                for several purposes:
                <ul>
                    <li>exploring and understanding the structure of match objects
                        generated by the <code>re</code> module, making Kiki a valuable
                        tool for people new to regexes
                    </li>
                    <li>testing regexes on sample text before deploying them in code
                    </li>
                </ul>
                Kiki can function on its own or as plugin for the 
                <a href="http://spe.pycs.net">Spe</a> Python editor.
                <br /><br />
            </td></tr>
            
            <tr><td bgcolor="#EAEAEA">
                <b><font size="4">Working with Kiki</font></b>
            </td></tr>
            <tr><td>
                Enter the regex in the combo box and hit Evaluate to run it against
                the text in the <i>Sample text</i> tab. The results appear in the
                <i>Matches</i> tab. You can use the list in the Help tab to view
                the built-in documentation about regular expressions. This documentation
                comes from the Python help files.
                <br /><br />
                Kiki automatically stores its settings and the last used sample text/regex
                in between sessions. During a session, all regexes which have been evaluated
                and have returned matches, are also stored in the combo box where the regex
                is entered, so you may experiment with e.g. adapted versions without losing
                a more primitive regex that already kinda works.
                <br /><br />
            </td></tr>
            
            <tr><td bgcolor="#EAEAEA">
                <b><font size="4">Options</font></b>
            </td></tr>
            <tr><td>
                <dl>
                  <dt><b>Methods</b></dt>
                  <dd>Use <i>Find all</i> to get all non-overlapping matches
                      of the regex, or <i>Find first</i> to get only the first match (equivalent
                      to the <code>search</code> method of regular expression objects).
                  </dd>
                  <dt><b>Flags</b></dt>
                  <dd>Determines which flags the regex should be compiled with.
                  </dd>
                </dl>
                <br />
                
            </td></tr>
            
            <tr><td bgcolor="#EAEAEA">
                <b><font size="4">Understanding the output</font></b>
            </td></tr>
            <tr><td>
                Kiki's output is quite extensive and provides color-coded information on the results
                of the match. Let's assume you're trying to match the regex 
                <code><font color="teal">fer(re)*t</font></code> against
                the sample text 
                <code><font color="purple"><i>Kiki the ferret - as nifty as ferrets get</i></font></code>.
                The results of a <i>Find all</i> evaluation by default looks something like this:
                <br /><br />
                <table cellpadding="0" cellspacing="0">
                  <tr><td bgcolor="#F8F8F8">
                    <font color="#777777">Kiki&nbsp;the&nbsp;<font color="#000000"><b><u><b><font size="0">0:</font></b></u><font color="#0000AA"><b>(</b></font>fer<font color="#00AA00"><b>(</b></font>re<font color="#00AA00"><b>)</b><font size="0">1</font></font>t<font color="#0000AA"><b>)</b><font size="0">0</font></font></b></font>&nbsp;-&nbsp;as&nbsp;nifty&nbsp;as&nbsp;<font color="#000000"><b><u><b><font size="0">1:</font></b></u><font color="#0000AA"><b>(</b></font>fer<font color="#00AA00"><b>(</b></font>re<font color="#00AA00"><b>)</b><font size="0">1</font></font>t<font color="#0000AA"><b>)</b><font size="0">0</font></font></b></font>s&nbsp;get</font>
                  </td></tr>
                </table><br />
                <br />
                Each <i>match</i> is prepended by a small, underlined number: this is the index of the 
                corresponding <i>match object</i> in the list
                of match objects found in the sample text. In the example above, there are two match objects, 
                with indexes 
                <font size="0"><b><u>0</u></b></font> and <font size="0"><b><u>1</u></b></font>.
                <br /><br />
                Within each match, colored parentheses show where a match group starts and ends. Group 
                <font color="#0000AA"><b>(</b></font><font color="#0000AA"><b>)<font size="0">0</font></b></font> 
                represents the entire match. In this example we have also created an extra group because of the
                use of <code><font color="teal">(re)*</font></code>". This is made visible by the green parentheses bearing the
                index 1: 
                <font color="#00AA00"><b>(</b></font><font color="#00AA00"><b>)</b><font size="0">1</font></font>.
                <br /><br />
                Pay attention to an interesting property of these groups: some of them might not contribute to the match
                and are then skipped in the output (in the match object, these groups start and end at position -1).
                An example: let's find all sentences talking about expecting the Spanish Inquisition in the text below:
                <br /><br />
                <code><font color="purple"><i>
                Chapman: I didn't expect a kind of Spanish Inquisition.
                <br /><br />
                (JARRING CHORD - the cardinals burst in)
                <br /><br />
                Ximinez: NOBODY expects the Spanish Inquisition! Our chief weapon is surprise...surprise and fear...fear and surprise.... 
                         Our two weapons are fear and surprise...and ruthless efficiency.... 
                         Our *three* weapons are fear, surprise, and ruthless efficiency...and an almost fanatical devotion to the Pope.... 
                         Our *four*...no... *Amongst* our weapons.... Amongst our weaponry...are such elements as fear, surprise.... 
                         I'll come in again. (Exit and exeunt)
                </i></font></code>
                <br /><br />
                For this purpose, we can use e.g. the following regex:
                <br /><br />
                <code><font color="teal">([a-zA-Z']+\s)+?expect(.*?)(the )*Spanish Inquisition(!|.)</font></code>
                <br /><br />
                The result is:
                <br /><br />
                <table cellpadding="0" cellspacing="0">
                  <tr><td bgcolor="#F8F8F8">
                    <font color="#777777">Chapman: 
                    <font color="#000000"><b><u><b><font size="0">0:</font></b></u><font color="#0000AA"><b>(</b></font>I 
                    <font color="#00AA00"><b>(</b></font>didn't 
                    <font color="#00AA00"><b>)</b><font size="0">1</font></font>expect<font color="#FFAA55"><b>(</b></font> 
                    a kind of <font color="#FFAA55"><b>)</b><font size="0">2</font></font>Spanish 
                    Inquisition<font color="#00AAAA"><b>(</b></font>.<font color="#00AAAA"><b>)</b><font size="0">4</font></font><font color="#0000AA"><b>)</b><font size="0">0</font></font></b></font><br /><br />(JARRING 
                    CHORD - the cardinals burst in)
                    <br /><br />                  
                    <font color="#777777"> Ximinez: 
                    <font color="#000000"><b><u><b><font size="0">1:</font></b></u><font color="#0000AA"><b>(</b></font><font color="#00AA00"><b>(</b></font>NOBODY 
                    <font color="#00AA00"><b>)</b><font size="0">1</font></font>expect<font color="#FFAA55"><b>(</b></font>s 
                    <font color="#FFAA55"><b>)</b><font size="0">2</font></font><font color="#AA0000"><b>(</b></font>the 
                    <font color="#AA0000"><b>)</b><font size="0">3</font></font>Spanish 
                    Inquisition<font color="#00AAAA"><b>(</b></font>!<font color="#00AAAA"><b>)</b><font size="0">4</font></font><font color="#0000AA"><b>)</b><font size="0">0</font></font></b></font> 
                    Our chief weapon is surprise...surprise and fear...fear and surprise.... 
                    Our two weapons are fear and surprise...and ruthless efficiency.... 
                    Our *three* weapons are fear, surprise, and ruthless efficiency...and an 
                    almost fanatical devotion to the Pope.... Our *four*...no... *Amongst* our 
                    weapons.... Amongst our weaponry...are such elements as fear, surprise.... 
                    I'll come in again. (Exit and exeunt)
                  </td></tr>
                </table><br />
                <br />
                The interesting part is what's going on in the match with index <u><b><font size="0">0</font></b></u>:
                between the group with index <font color="#FFAA55"><font size="0"><b>2</b></font></font>
                and the one with index <font color="#00AAAA"><font size="0"><b>4</b></font></font>, 
                the group with index <font color="#AA0000"><font size="0"><b>3</b></font></font>
                has disappeared. This group matches an optional <code><font color="purple"><i>the</i></font></code> which
                is not present in this case. In other words, the group exists, but does not contribute 
                to the match and is therefore not displayed.
                <br /><br />
            </td></tr>
        </table>
    </body>
</html>